Proxy (instrumental) SVAR Modeling
==================================

A ``proxy_svar`` object is a structural VAR identified with **external
instruments** ("proxies"): observed series that are correlated with a
structural shock of interest but with no other shock. It extends the ``svar``
object, so data handling, estimation, forecasting and the various
decompositions are exactly as described in :doc:`../SVAR_capabilities/Main Structural VAR Modeling`
and :doc:`../ReducedFormVAR_capabilities/Main Reduced form VAR Modeling`; this
page covers what is specific to the proxy case.

The model
---------

The structural VAR is as usual,

.. math::

	A_{0}\left( r_{t}\right) y_{t}=C\left( r_{t}\right) x_{t}+A_{1}\left(
	r_{t}\right) y_{t-1}+...+A_{p}\left( r_{t}\right) y_{t-p}+\varepsilon _{t},

and each proxy :math:`m_{t}` is linked to one structural shock by

.. math::

	m_{t}=\beta _{m}\left( r_{t}\right) \varepsilon _{y,t}+\sigma _{m}\left(
	r_{t}\right) \varepsilon _{m,t},

with :math:`r_{t}=1,2,...,h` and transition probabilities
:math:`p_{r_{t},r_{t+1}}\left( I_{t}\right)`. Here :math:`\varepsilon_{y,t}` is
the structural shock the proxy instruments, :math:`\varepsilon_{m,t}` is proxy
measurement noise, :math:`\beta_{m}` the relevance coefficient and
:math:`\sigma_{m}` the noise scale. The proxy series themselves are part of the
:doc:`time-series database <../DataManagement/Data Management>` passed to
``estimate``.

Creating a proxy SVAR
---------------------

The proxy structure is the first argument; the rest of the signature is the
``svar`` one::

	mdl = proxy_svar(proxies, varlist)
	mdl = proxy_svar(proxies, varlist, exog, nlags, constant, markov_chains)

``proxies`` is an array of structs, one per instrument, with fields:

- ``var`` -- name of the endogenous variable whose shock the proxy instruments;
- ``eqtn`` -- the proxy-equation number (matching the declaration order of ``var``);
- ``coef`` -- the name of the proxy relevance coefficient (:math:`\beta_{m}` above);
- ``shock_eqtn`` -- the equation whose structural shock is related to the proxy.

For example, to instrument the monetary-policy shock (the shock in the ``R``
equation) with a high-frequency surprise series ``mp_surprise``::

	prox        = struct();
	prox.var    = 'R';
	prox.eqtn   = 1;
	prox.coef   = 'beta_mp';
	prox.shock_eqtn = 'R';

	endog = {'R','PAI','GROWTH'};

	mdl = proxy_svar(prox, endog, {}, 4, true);

(``varlist`` must be ordered consistently with the proxy specification.)

Estimation, IRFs, decompositions, forecasting
---------------------------------------------

These are called exactly as for an ``svar`` -- ``estimate`` (with an optional
prior and any additional identifying restrictions on ``a0``/``a1``/...),
``print_structural_form``, ``irf``, ``variance_decomposition``,
``historical_decomposition``, ``forecast``, ``bootstrap`` -- the proxy
relevance and noise parameters (``beta_*``, ``sigma_*``) are estimated
alongside the VAR coefficients, and the proxy equations supply the
identification of the instrumented shock(s). See the structural- and
reduced-form VAR chapters for the call patterns and the plotting helpers.

Adding regime switching
-----------------------

A Markov-chain structure can be passed as the last argument, as for the
``svar`` object; the proxy relevance and noise (:math:`\beta_{m}`,
:math:`\sigma_{m}`) and/or the VAR coefficients can be made regime-dependent
through ``controlled_parameters``, and time-varying transition probabilities
are specified exactly as in the reduced-form VAR chapter.

.. todo::

   Add a full worked example (data, multiple proxies, estimation, identified
   IRFs with confidence bands, and a regime-switching variant).

Technical documentation for proxy_svar objects
----------------------------------------------

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   proxy_svar_properties_methods